APP_USER_DIR

The APP_USER_DIR function provides access to the IDL application user directory. The application user directory is a location where IDL, and applications written in IDL, can store user-specific data that will persist between IDL sessions. For example, the IDL iTools store user-specified preferences, styles, and macros in the application user directory.

The application user directory is created automatically by IDL as a subdirectory (named .idl) of the user’s home directory.

To prevent unrelated applications from encountering each other’s files, the .idl directory is organized into subdirectories with names specified by the application author. For example, files used by applications distributed with IDL are stored in a subdirectories of .idl named envi and idl. Inside each author’s subdirectory, files are organized by application and (optionally) by a combination of attributes of the IDL version that creates the directory.

The organization of the .idl directory is opaque to both users and authors of IDL applications. Application authors are expected to manage the directory exclusively using the APP_USER_DIR function, and application users generally do not need to manually modify the files it contains.

APP_USER_DIR simplifies cross-platform application development by providing a well-defined location for IDL applications to store their resource files, regardless of the platform or version of IDL. The uniform organization it enforces is also a benefit for IDL users, since it makes it easier for them to understand the meaning and importance of the files found in their .idl directory.

Directories created by APP_USER_DIR have the following features:

• Each author of IDL applications has a unique area underneath the .idl directory. Different authors do not share space with each other, or with IDL distribution files.
• By default, an application directory is shared by all instances of the application. The application author can use RESTRICT keywords to specify that the directory only be used by a specified version of the application, or when running on a version of IDL with specified attributes such as release, operating system, hardware platform, etc.
• A README file is automatically generated for each author and application directory, following a standard format. The application author is required to supply the body text for the application README file (text for the author README file is optional, but recommended). The text is expected to explain the purpose of the directory, and supply contact information for the author. Each README file has a version associated with it, allowing APP_USER_DIR to automatically update the file as necessary.

APP_USER_DIR performs the following operations, in order:

1. If the specified author directory does not exist, it is created.
2. If the specified author directory does not have a standard README file, it is created. If there is an existing README file with a version number that is lower than the specified number, the file is replaced.
3. If the specified application subdirectory does not exist within the author directory, it is created.
4. If the specified application directory does not have a standard README file, it is created. If there is an existing README file with a version number that is lower than the specified number, the file is replaced.
5. The path to the application directory is returned as the value of the APP_USER_DIR function.

Other than the README file, the contents of an application directory are entirely up to the application author. The APP_USER_DIR function does not manage the content, only its location. The FILEPATH function can be used to construct filenames within the application directory, and IDL’s many input/output and file manipulation routines can be used to create and manage application specific content within it.

Syntax

Result = APP_USER_DIR(AuthorDirname, AuthorDesc, AppDirname, AppDesc, AppReadmeText, AppReadmeVersion [, AUTHOR_README_TEXT=string] [, AUTHOR_README_VERSION=integer] [, RESTRICT_APPVERSION=string] [, /RESTRICT_ARCH] [, /RESTRICT_FAMILY] [, /RESTRICT_FILE_OFFSET_BITS] [, /RESTRICT_IDL_RELEASE] [, /RESTRICT_MEMORY_BITS] [, /RESTRICT_OS] )

Return Value

Returns a string containing the path to the directory to be used by the calling application.

The directory and all associated README files are created if they do not exist. If the README files exit, they will be updated if the values of AppReadmeVersion and the AUTHOR_README_VERSION keyword are greater than those of the existing README files.

Arguments

AuthorDirname

A string specifying the name of the author directory to be used by the calling application. Use caution and pick a unique name unlikely to conflict with others.

In choosing AuthorDirname, consider the following:

1. AuthorDirname is case insensitive, regardless of the operating system platform. APP_USER_DIR will convert the name to lower case before creating the directory or returning its path string.
2. Keep the name short to minimize the chance that the full directory name is longer than the maximum supported length on the current platform.
3. The following characters are automatically converted to underscores (_) when creating the directory name: - ) ( . : > < as well as space and tab.

If AuthorDirname is an empty string, then the default product name will be used. This default is "idl" unless the IDL_PREF_DIR preference has been set.

AuthorDesc

A one-line description of the author, in human-readable form. This string is used for the header of the README file within the author directory.

AppDirname

The name of the application directory to be used by the calling application. For example, the IDL iTools application uses the application directory name “itools”.

APP_USER_DIR modifies the AppDirname string you specify in the same way it modifies the AuthorDirname string. See AuthorDirname, above.

AppDesc

A string specifying a brief description of the application in human-readable form. This string is used for the header of the README file within the application directory. For example, the AppDesc for the IDL iTools application is “IDL Intelligent Tools (iTools)”.

AppReadmeText

A string or string array giving the text used as the body of the README file within the application directory. The README text is for the benefit of IDL users who are trying to understand what the directory is for, and is expected to supply the following information:

• The identity of the author, and author contact information.
• A brief description of what the application is, and what it does.
• Any special rules governing if and when the user is allowed to delete the directory and its contents.

AppReadmeVersion

An integer greater than zero containing the version number of the README file.

Initially, AppReadmeVersion should be set to one. Every time you modify the text supplied as the AppReadmeText argument, increment the value of AppReadmeVersion by one. APP_USER_DIR uses this information to ensure that existing README files are automatically updated to the latest version.

The application README file version is different from, and unrelated to, the application version (as specified via the RESTRICT_APPVERSION keyword). The README version applies only to the contents of the README file. You might want to change the text in a README file without changing the version of the application; perhaps to clarify existing information or update your contact information.

Keywords

AUTHOR_README_TEXT

Supplies the README text for the author directory. Authors with multiple IDL applications should consider providing application-independent contact information here.

APP_USER_DIR requires you to supply text for the body of the application directory README file. You are not required to supply text for the author directory README file, but supplying such text is strongly recommended.

If you include this keyword, use the AUTHOR_README_VERSION keyword to supply a version number for the README file.

AUTHOR_README_VERSION

The version number for the author README file; must be greater than zero, the default is 1.

Initially, AUTHOR_README_VERSION should be explicitly specified and set equal to one. Every time you modify the text supplied as the AUTHOR_README_TEXT keyword, increment the value of AUTHOR_README_VERSION by one. APP_USER_DIR uses this information to ensure that existing author README files are automatically updated to the latest version.

The author README file version is different from, and unrelated to, the application version (as specified via the RESTRICT_APPVERSION keyword). The README version applies only to the contents of the README file.

RESTRICT_APPVERSION

An arbitrary string giving the application version. Different application user directories will be created for different values of this keyword.

In choosing your version string, consider the same details described for the AppDirname argument apply to RESTRICT_APPVERSION.

RESTRICT_ARCH

Specifies that different application user directories be created when your application runs on systems with different hardware architectures, as reported by the !VERSION.ARCH system variable field.

RESTRICT_FAMILY

Specifies that different application user directories be created when your application runs on systems running different operating system families, as reported by the !VERSION.OS_FAMILY system variable field.

If RESTRICT_OS is also specified, RESTRICT_FAMILY is ignored and has no effect.

RESTRICT_FILE_OFFSET_BITS

Specifies that different application user directories be created when your application runs on versions of IDL that use a different number of file offset bits, as reported by the !VERSION.FILE_OFFSET_BITS system variable field.

RESTRICT_IDL_RELEASE

Specifies that different application user directories be created when your application runs under different versions of IDL, as specified by the !VERSION.RELEASE system variable field.

RESTRICT_MEMORY_BITS

Specifies that different application user directories be created when your application runs on versions of IDL that use a different number of memory address bits, as reported by the !VERSION.MEMORY_BITS system variable field.

RESTRICT_OS

Set this keyword to specify that different application user directories be created when your application runs on systems running different operating systems, as reported by the !VERSION.OS system variable field.

If RESTRICT_OS is also specified, RESTRICT_FAMILY is ignored and has no effect.

Examples

The following function demonstrates how APP_USER_DIR can be used efficiently to create an application user directory for an IDL application supporting the “Amazing” Grill System (AGS), a product of the fictional Acme Widgets, Inc. We assume that each AGS application user directory should only be shared between instances of the same version of the application that are running under the same operating system family. The use of the RESTRICT keywords causes the AGS software to create a different application user directory for each unique combination of these two attributes. The rest of the application can call this function as many times as desired. It ensures that the necessary directory exists on the first call, and then returns the path string on subsequent calls:

FUNCTION acme_grill_config_dir

 

   COMMON acme_grill_common, config_dir

 

   IF (N_ELEMENTS(config_dir) NE 1) THEN BEGIN

 

      ; Increment if author_readme_text is changed

      author_readme_version = 1

 

      author_readme_text = $

         ['This is the user configuration directory for', $

         'IDL based products from Acme Widgets, Inc:', $

         '', $

         ' Acme Widgets, Inc.', $

         ' 1234 Amazing Way', $

         ' Grill Valley, NV, 12345', $

         ' USA', $

         '', $

         'Thank you for using products from Acme Widgets, Inc.' ]

 

      ; Increment if app_readme_text is changed

      app_readme_version = 1

 

      app_readme_text = $

         ['This is the configuration directory for the', $

         'Acme "Amazing" Grill System. It is used to', $

         'remember grill settings in between grill', $

         'invocations.', $

         '', $

         'It is safe to remove this directory, as it', $

         'will be recreated on demand. Note that all', $

         'settings (e.g. smoke injection depth, juicitron', $

         'angle, etc.) will revert to their default settings.', $

         '', $

         'Thank you for using the Acme "Amazing" Grill System.']

 

      config_dir = APP_USER_DIR('acme', 'Acme Widgets, Inc.', $

         'acme_grill', 'The Acme "Amazing" Grill System', $

         app_readme_text, app_readme_version, $

         AUTHOR_README_TEXT=author_readme_text, $

         AUTHOR_README_VERSION=author_readme_version, $

         RESTRICT_APPVERSION='1.0', /RESTRICT_FAMILY)

 

   ENDIF

 

   RETURN, config_dir

 

END

Version History

6.1	Introduced

See Also

APP_USER_DIR_QUERY, FILE_MKDIR, FILE_TEST, FILEPATH, OPENR/OPENU/OPENW, !VERSION system variable